package com.smart.community.work.service;

import com.baomidou.mybatisplus.core.metadata.IPage;
import com.baomidou.mybatisplus.extension.service.IService;
import com.smart.community.work.dto.NotificationDTO;
import com.smart.community.work.entity.Notification;
import com.smart.community.work.vo.NotificationVO;

import java.time.LocalDate;
import java.util.List;
import java.util.Map;

/**
 * 消息通知服务接口
 * 
 * 严格按照《Java后端SpringBoot代码开发规范_重构版.md》Service规范实现：
 * - 继承IService：获得基础CRUD方法
 * - 方法命名：使用动词+名词形式，语义明确
 * - 参数验证：使用@Valid注解进行参数验证
 * - 异常处理：使用统一的异常处理机制
 * - 完整注释：所有方法都有完整的JavaDoc注释
 * 
 * @author Wu.Liang
 * @since 2025-01-30
 * @version 1.0.0
 */
public interface NotificationService extends IService<Notification> {

    /**
     * 分页查询消息通知
     *
     * @param current 当前页
     * @param size 每页大小
     * @param params 查询参数
     * @return 消息通知分页数据
     */
    IPage<NotificationVO> selectNotificationPage(Integer current, Integer size, Map<String, Object> params) throws Exception;

    /**
     * 根据ID查询消息通知详情
     *
     * @param id 消息通知ID
     * @return 消息通知详情
     */
    NotificationVO selectNotificationById(Long id) throws Exception;

    /**
     * 创建消息通知
     *
     * @param notificationDTO 消息通知DTO
     * @return 创建结果
     */
    Boolean createNotification(NotificationDTO notificationDTO) throws Exception;

    /**
     * 批量创建消息通知
     *
     * @param notificationDTO 消息通知DTO
     * @return 创建结果
     */
    Boolean batchCreateNotification(NotificationDTO notificationDTO) throws Exception;

    /**
     * 更新消息通知
     *
     * @param notificationDTO 消息通知DTO
     * @return 更新结果
     */
    Boolean updateNotification(NotificationDTO notificationDTO) throws Exception;

    /**
     * 删除消息通知
     *
     * @param id 消息通知ID
     * @return 删除结果
     */
    Boolean deleteNotification(Long id) throws Exception;

    /**
     * 批量删除消息通知
     *
     * @param ids 消息通知ID列表
     * @return 删除结果
     */
    Boolean batchDeleteNotification(List<Long> ids) throws Exception;

    /**
     * 根据接收人ID查询消息通知
     *
     * @param receiverId 接收人ID
     * @param propertyCompanyId 物业公司ID
     * @return 消息通知列表
     */
    List<NotificationVO> selectNotificationByReceiverId(Long receiverId, Long propertyCompanyId) throws Exception;

    /**
     * 根据发送人ID查询消息通知
     *
     * @param senderId 发送人ID
     * @param propertyCompanyId 物业公司ID
     * @return 消息通知列表
     */
    List<NotificationVO> selectNotificationBySenderId(Long senderId, Long propertyCompanyId) throws Exception;

    /**
     * 查询未读消息数量
     *
     * @param receiverId 接收人ID
     * @param propertyCompanyId 物业公司ID
     * @return 未读消息数量
     */
    Integer selectUnreadCount(Long receiverId, Long propertyCompanyId) throws Exception;

    /**
     * 查询指定类型的未读消息数量
     *
     * @param receiverId 接收人ID
     * @param propertyCompanyId 物业公司ID
     * @param type 消息类型
     * @return 未读消息数量
     */
    Integer selectUnreadCountByType(Long receiverId, Long propertyCompanyId, Integer type) throws Exception;

    /**
     * 查询用户指定时间段的消息通知
     *
     * @param receiverId 接收人ID
     * @param propertyCompanyId 物业公司ID
     * @param startDate 开始日期
     * @param endDate 结束日期
     * @return 消息通知列表
     */
    List<NotificationVO> selectNotificationByReceiverIdAndDateRange(Long receiverId, Long propertyCompanyId, LocalDate startDate, LocalDate endDate) throws Exception;

    /**
     * 查询紧急消息
     *
     * @param receiverId 接收人ID
     * @param propertyCompanyId 物业公司ID
     * @return 紧急消息列表
     */
    List<NotificationVO> selectUrgentNotifications(Long receiverId, Long propertyCompanyId) throws Exception;

    /**
     * 查询置顶消息
     *
     * @param receiverId 接收人ID
     * @param propertyCompanyId 物业公司ID
     * @return 置顶消息列表
     */
    List<NotificationVO> selectPinnedNotifications(Long receiverId, Long propertyCompanyId) throws Exception;

    /**
     * 标记消息为已读
     *
     * @param id 消息通知ID
     * @return 标记结果
     */
    Boolean markAsRead(Long id) throws Exception;

    /**
     * 批量标记消息为已读
     *
     * @param ids 消息通知ID列表
     * @return 标记结果
     */
    Boolean batchMarkAsRead(List<Long> ids) throws Exception;

    /**
     * 标记所有消息为已读
     *
     * @param receiverId 接收人ID
     * @param propertyCompanyId 物业公司ID
     * @return 标记结果
     */
    Boolean markAllAsRead(Long receiverId, Long propertyCompanyId) throws Exception;

    /**
     * 设置消息置顶
     *
     * @param id 消息通知ID
     * @param pinned 是否置顶
     * @return 设置结果
     */
    Boolean setPinned(Long id, Boolean pinned) throws Exception;

    /**
     * 设置消息紧急
     *
     * @param id 消息通知ID
     * @param urgent 是否紧急
     * @return 设置结果
     */
    Boolean setUrgent(Long id, Boolean urgent) throws Exception;

    /**
     * 查询消息统计信息
     *
     * @param propertyCompanyId 物业公司ID
     * @param startDate 开始日期
     * @param endDate 结束日期
     * @return 统计信息
     */
    Map<String, Object> selectNotificationStatistics(Long propertyCompanyId, LocalDate startDate, LocalDate endDate) throws Exception;

    /**
     * 根据关联业务查询消息
     *
     * @param relatedId 关联业务ID
     * @param relatedType 关联业务类型
     * @return 消息通知列表
     */
    List<NotificationVO> selectNotificationByRelatedId(Long relatedId, String relatedType) throws Exception;

    /**
     * 删除过期消息
     *
     * @return 删除数量
     */
    Integer deleteExpiredNotifications() throws Exception;

    /**
     * 获取消息类型列表
     *
     * @return 消息类型列表
     */
    List<Map<String, Object>> selectNotificationTypeList() throws Exception;

    /**
     * 发送系统通知
     *
     * @param title 标题
     * @param content 内容
     * @param receiverIds 接收人ID列表
     * @param type 消息类型
     * @param relatedId 关联业务ID
     * @param relatedType 关联业务类型
     * @return 发送结果
     */
    Boolean sendSystemNotification(String title, String content, List<Long> receiverIds, 
                                 Integer type, Long relatedId, String relatedType) throws Exception;
}
